Repository navigation
Serve English in place of untranslated locale routes - #2214
David Pine (IEvangelist) merged 12 commits into
Conversation
Untranslated locale routes are no longer built (~650 English copies per locale,
~3 GB of dist). StaticHost serves the English page in place at the locale URL,
and a small client script localizes the chrome and shows the untranslated notice.
- Starlight patch: skip fallback routes in getStaticPaths.
- /locale-fallback/{locale}.json UI dictionaries and locales.json manifest.
- hreflang alternates only list real translations.
- StaticHost LocaleFallbackMiddleware (rewrite, Content-Language: en, in-locale
redirects) sharing the canonical path index; astro dev mirrors it.
- Unit, StaticHost, and E2E tests.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Combined validation: real
|
| Before | After all four PRs | |
|---|---|---|
Ev2ServiceArtifactsRoot/Images/aspiredev.tar.gz |
~4 GB | 1.76 GB |
| Built HTML pages | 38,344 | 29,134 |
Site output (dist) |
9.8 GB | 3.73 GB |
wwwroot in image |
n/a | 3.73 GB originals + 0.68 GB .br |
The container starts in 11 s, /healthz returns 200, and idle memory is about 2 GB, likely from the 134 MB staticwebassets.endpoints.json.
Testing against the container
- Layout check: 35 representative layouts (docs, splash, hub, 404,
/de/fallback,/ja/translated, C#/TS/Go API landing, package, type and member pages) on desktop and mobile. Every page returned the expected status, with no failed requests and no page errors. - Full Playwright suite,
CI=1 bunx playwright test, all 3 projects, reusing the container on :4322: 1,632 passed, 5 failed, 2 flaky, 107 skipped. Failures are triaged below. - Manual testing of the running container found no issues.
This PR: saves about 3 GB of dist. Untranslated /de/... pages are served in place with German chrome and theDieser Inhalt ist noch nicht in deiner Sprache verfügbar.banner;Content-Language: en;/de/x.mdworks. The combined build found that the links validator rejected 148 locale links to routes that are no longer built. That's fixed here in 0b3a81b plus tests in 58d80e9. Known follow-up: redirect pages under/de/forward to the English URL (previously these returned 404).
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
CI starts StaticHost before it unpacks the site, so reading the locale manifest at startup left the fallback disabled and every untranslated locale route returned 404. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Clients fetch /locale-fallback/{locale}.json?v=<hash>, a short SHA-256 of the
emitted dictionaries, so the edge can cache them indefinitely.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…partial web root StaticHost starts before CI unpacks the site and treats the locale manifest as the sign that the web root is complete. Extracting it under a temporary name and moving it into place afterwards closes a race that left pages 404ing for a whole E2E shard. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- Rename CanonicalPathRedirectExtensions to StaticRoutingExtensions now that it also wires locale fallback. - Check for the locale manifest before scanning the web root and rescan if it appears mid-scan, so a partial snapshot is never marked final. - Validate links to translated locale pages instead of excluding them whenever the English page exists. - Leave configured redirect sources to Astro in the dev locale fallback rewrite. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…le-fallback-served-in-place # Conflicts: # src/frontend/patches/@astrojs__starlight@0.41.3.patch # src/frontend/patches/README.md
There was a problem hiding this comment.
🟡 Changes recommended
Localization still leaves accessible-name language, initialized tooltips, and lazy-loaded search controls incorrect, while client-side navigation and cached-dictionary behavior lack test coverage.
4 open issues
What changed in this PR
Reduces the frontend build size by serving English pages at untranslated locale URLs instead of generating duplicate pages. Client-side dictionaries localize navigation and interface labels while preserving English content.
Changes:
- Skip untranslated Starlight routes and limit hreflang alternates to real translations.
- Add StaticHost and development-server fallback routing, including Markdown support.
- Add localized interface dictionaries, fallback notices, tests, and CI extraction coordination.
| File | Description |
|---|---|
tests/StaticHost.Tests/LocaleFallbackTests.cs |
Tests fallback routing, redirects, Markdown, and index refresh. |
tests/StaticHost.Tests/AgentReadinessTestServer.cs |
Adds fallback middleware to the test pipeline. |
src/statichost/StaticHost/Routing/StaticWebRootIndex.cs |
Shares a retryable static-file index. |
src/statichost/StaticHost/Routing/StaticRoutingExtensions.cs |
Registers routing middleware with the shared index. |
src/statichost/StaticHost/Routing/LocaleFallbackResolver.cs |
Resolves locale requests to English files. |
src/statichost/StaticHost/Routing/LocaleFallbackMiddleware.cs |
Applies fallback rewrites and language headers. |
src/statichost/StaticHost/Routing/CanonicalPathResolver.cs |
Exposes existing-path lookup. |
src/statichost/StaticHost/Routing/CanonicalPathRedirectMiddleware.cs |
Uses the shared path index. |
src/statichost/StaticHost/Routing/CanonicalPathRedirectExtensions.cs |
Removes registration superseded by shared extensions. |
src/statichost/StaticHost/Program.cs |
Enables fallback before content-serving middleware. |
src/frontend/tests/unit/route-data-middleware-hreflang.vitest.test.ts |
Updates alternate-language expectations. |
src/frontend/tests/unit/locale-fallback.vitest.test.ts |
Tests dictionaries, links, and route helpers. |
src/frontend/tests/e2e/og-metadata.spec.ts |
Removes expectations for generated fallback pages. |
src/frontend/tests/e2e/locale-fallback.spec.ts |
Checks fallback rendering and localized interface text. |
src/frontend/src/utils/translated-routes.ts |
Identifies routes backed by translations. |
src/frontend/src/utils/locale-fallback.ts |
Defines dictionary and localization helpers. |
src/frontend/src/utils/locale-fallback-version.ts |
Generates dictionary content hashes. |
src/frontend/src/utils/locale-fallback-dictionary.ts |
Builds localized interface dictionaries. |
src/frontend/src/scripts/locale-fallback.ts |
Localizes interface text, links, and notices. |
src/frontend/src/route-data-middleware.ts |
Removes untranslated hreflang alternates. |
src/frontend/src/pages/locale-fallback/locales.json.ts |
Emits the supported-locale manifest. |
src/frontend/src/pages/locale-fallback/[locale].json.ts |
Emits per-locale dictionaries. |
src/frontend/src/env.d.ts |
Declares the translated-route build constant. |
src/frontend/src/components/starlight/PageTitle.astro |
Adds the fallback-notice template and styling. |
src/frontend/src/components/starlight/Head.astro |
Includes fallback support on English pages. |
src/frontend/src/components/LocaleFallback.astro |
Preloads dictionaries and temporarily hides untranslated interface elements. |
src/frontend/patches/README.md |
Documents the expanded Starlight patch. |
src/frontend/patches/@astrojs__starlight@0.41.3.patch |
Excludes fallback routes from generated pages. |
src/frontend/config/translated-paths.mjs |
Collects translated routes from content files. |
src/frontend/config/locale-fallback-dev-integration.mjs |
Adds development-server fallback rewrites. |
src/frontend/config/links-validator-exclude.mjs |
Recognizes valid fallback destinations during link validation. |
src/frontend/astro.config.mjs |
Wires route data, validation, and development integration. |
.github/workflows/frontend-build.yml |
Publishes the manifest after site extraction completes. |
Review effort: Balanced
…pages - Update Tippy tooltip content (and its language) when the dictionary arrives after tooltips initialized. - Set lang on icon-only controls whose attributes are translated. - Defer Pagefind initialization until the fallback dictionary localizes site-search's data-translations and data-ui-lang, keeping the English index. - Add E2E coverage for tooltips, icon-only lang, the lazily initialized search UI, and click-driven ClientRouter navigation across translated, fallback, and English pages. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Switching <html lang> while Pagefind UI mounted didn't localize its strings. Read Pagefind's per-language UI strings from the installed @pagefind/default-ui at build time, include them in the fallback dictionary's search translations, and drop the lang switch from the Starlight patch. The English index is unchanged. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Summary
Part of a series of changes to shrink the frontend container image (the Astro
distis about 9.8 GB). This one targets untranslated locale pages.Today Starlight builds a full English copy of every page for each locale that hasn't translated it. That's roughly 650 pages per locale across 13 locales, about 3 GB. Only
jahas real translations. This PR stops building those copies. StaticHost serves the English page at the locale URL instead, without a redirect, and a small script switches the menus and labels to the reader's language and shows the "not translated" notice.patches/@astrojs__starlight@0.41.3.patch):getStaticPathsskips fallback routes (isFallback). Starlight's internal route list is unchanged, so sidebars and pagination still link within the locale. Upstream request for a configurable option: Option to skip generating fallback pages for untranslated content withastro/starlight#4419. The local patch stays until that ships.config/translated-paths.mjsbuilds the list fromsrc/content/docs/{locale}and passes it in through the__ASPIRE_TRANSLATED_PATHS__define.route-data-middleware.tsdrops hreflang alternates that point to untranslated locale URLs. Canonical URLs stay English./locale-fallback/{locale}.jsonmaps English interface text to each locale. It covers Starlight and plugin UI strings, our custom i18n keys, sidebar labels, translated page titles, and the untranslated-content notice./locale-fallback/locales.jsonlists the locales.LocaleFallbackMiddlewareruns after canonical-path redirects and before agent readiness, default files, and routing. When/{locale}/xdoesn't exist but/xdoes, it rewrites the path internally and setsContent-Language: en. A missing trailing slash or wrong casing gets a 308 redirect that keeps the locale. Markdown requests (Accept: text/markdownand/de/x.md) return the English Markdown. The middleware turns itself off when the manifest is missing. It shares the canonical path index, so the web root is scanned once.src/scripts/locale-fallback.tsswaps the text and aria-labels, inserts a notice styled like Starlight's, keeps menu and sidebar links in the locale, and handles in-site navigation without full page reloads.config/locale-fallback-dev-integration.mjsdoes the same rewrite inastro dev, so local runs match production.Known trade-off:
<html lang>staysen, and only translated elements getlang="{locale}". Setting the whole page to the locale would make Pagefind load that locale's index, which is now nearly empty. As a result, search results on/de/pages link to English URLs, and clicking one takes the reader out of the locale.Third-party links and affiliations
None. The only link points to the upstream Starlight discussion.
Validation
dotnet test tests/StaticHost.Tests: passed (380 tests, including 7 newLocaleFallbackTests).vitest run --config vitest.config.ts: 1511 passed, 1 failed (incremental-build.vitest.test.ts). It failed withspawn bun ENOENTbecause bun isn't on PATH on the dev machine. It also fails onmainthere, so it's unrelated to this change.locale-fallback,route-data-middleware-hreflang,route-data-middleware-sidebar-locale,locale-routes,language-switch, andastro-vite-config.playwright test(desktop-chromium and mobile-chromium againstastro dev) passed for:tests/e2e/locale-fallback.spec.tsapi-markdown-routes,dev-layout,og-metadata,search-visual-parity, andui-regressionsmobile-uxon/de/get-started/first-app/og-metadatacases expected built fallback pages (/da/and/uk/fundamentals/telemetry/). Those pages are no longer built, so I removed the cases.eslintpassed on the changed files.prettier --checkpassed with--end-of-line auto, because the working copy has CRLF line endings.bun run buildlocally. CI will run the first full build and the first E2E run against StaticHost.